home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 38 / Amiga Format CD38 (1999-03-15)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-04].iso / -in_the_mag- / reader_requests / dice_v3.15 / doc / fd.doc < prev    next >
Text File  |  1999-01-26  |  16KB  |  716 lines
  1.  
  2.     FD.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. fd/file_descriptor
  7. c.lib/fd/close
  8. c.lib/fd/creat
  9. c.lib/fd/fcntl
  10. c.lib/fd/fdtofh
  11. c.lib/fd/ioctl
  12. c.lib/fd/isatty
  13. c.lib/fd/lseek
  14. c.lib/fd/mkdir
  15. c.lib/fd/open
  16. c.lib/fd/read
  17. c.lib/fd/rmdir
  18. c.lib/fd/unlink
  19. c.lib/fd/write
  20.  
  21.  
  22. fd/file_descriptor                    fd/file_descriptor
  23.  
  24.     A file descriptor is the lowest portable access to the file system a
  25.     C program may make.  file descriptors are used with open, read, write,
  26.     close, etc...  A file descriptor is unbuffered (that is, every operation
  27.     goes to the kernel and does not get buffered locally).
  28.  
  29.     Remember that a file descriptor is different from a STDIO file pointer
  30.     (see the file_pointer manual page) and an AmigaDOS file handle.
  31.  
  32.  
  33. fd/close                        fd/close
  34.  
  35.    NAME
  36.     close - close a file descriptor
  37.  
  38.    SYNOPSIS
  39.     int r = close(fd);
  40.     int fd;
  41.  
  42.    FUNCTION
  43.     The specified file descriptor is closed.  If an error occurs on
  44.     close or the descriptor is invalid a non-zero return code will
  45.     result and errno will be set to the appropriate error condition.
  46.  
  47.    NOTE
  48.     refer to the file_descriptor manual page for general information
  49.  
  50.     Unlike file pointers and file handles, the file descriptor is
  51.     checked for validity and will simply return an error if illegal.
  52.  
  53.    EXAMPLE
  54.     #include <fcntl.h>
  55.  
  56.     main()
  57.     {
  58.         int fd;
  59.  
  60.         fd = open("T:xx", O_WRONLY|O_CREAT|O_TRUNC);
  61.         if (fd >= 0) {
  62.         puts("created empty file T:xx");
  63.         close(fd);
  64.         } else {
  65.         puts("unable to create T:xx");
  66.         }
  67.         return(0);
  68.     }
  69.  
  70.    INPUTS
  71.     int fd;     file descriptor to close, the file descriptor becomes
  72.             invalid after this call
  73.  
  74.    RESULTS
  75.     int r;        return value, 0 == ok, non-zero == error
  76.  
  77.    SEE ALSO
  78.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  79.     mkdir, open, read, rmdir, unlink, write
  80.  
  81.  
  82. fd/creat                        fd/creat
  83.  
  84.    NAME
  85.     creat - create a file
  86.  
  87.    SYNOPSIS
  88.     int fd = creat(file);
  89.     char *file;
  90.  
  91.    FUNCTION
  92.     Creates a new file and returns a file descriptor for it.  This call
  93.     is equivalent to open(file, O_CREAT|O_TRUNC|O_RDWR);
  94.  
  95.     This is an obsolete function and should not be used.
  96.  
  97.    NOTE
  98.     refer to the file_descriptor manual page for general information
  99.  
  100.     Unlike file pointers and file handles, the file descriptor is
  101.     checked for validity and will simply return an error if illegal.
  102.  
  103.    EXAMPLE
  104.     #include <fcntl.h>
  105.  
  106.     main()
  107.     {
  108.         int fd;
  109.  
  110.         fd = creat("T:xx");
  111.         if (fd >= 0) {
  112.         puts("created empty file T:xx");
  113.         close(fd);
  114.         } else {
  115.         puts("unable to create T:xx");
  116.         }
  117.         return(0);
  118.     }
  119.  
  120.    INPUTS
  121.     char *file;    nul terminated string that is the filename
  122.  
  123.    RESULTS
  124.     int fd;     file descriptor if >= 0, error if < 0.
  125.  
  126.    SEE ALSO
  127.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  128.     mkdir, open, read, rmdir, unlink, write
  129.  
  130.  
  131. fd/fcntl                        fd/fcntl
  132.  
  133.    NAME
  134.     fcntl - file control on a file
  135.  
  136.    SYNOPSIS
  137.     int r = fcntl(fd, req, arg)
  138.     int fd;
  139.     int req;
  140.     int arg;
  141.  
  142.    FUNCTION
  143.     fcntl() may be used to control various aspects of an FD and is a
  144.     higher level call than ioctl().
  145.  
  146.     CURRENTLY, NOTHING REAL IS DOABLE BY THE FCNTL() CALL for files.
  147.     However, fcntl fully supports programmer simulated file descriptors.
  148.  
  149.    NOTE
  150.     refer to the file_descriptor manual page for general information
  151.  
  152.     Unlike file pointers and file handles, the file descriptor is
  153.     checked for validity and will simply return an error if illegal.
  154.  
  155.    EXAMPLE
  156.     #include <fcntl.h>
  157.  
  158.    INPUTS
  159.     int fd;     file descriptor to operate on
  160.     int req;    request from <fcntl.h> (F_* defines)
  161.     int arg;    control argument
  162.  
  163.    RESULTS
  164.     int r;        result, error if less than 0.
  165.  
  166.    SEE ALSO
  167.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  168.     mkdir, open, read, rmdir, unlink, write
  169.  
  170.  
  171. fd/fdtofh                        fd/fdtofh
  172.  
  173.    NAME
  174.     fdtofh - return AmigaDOS file handle for file descriptor
  175.  
  176.    SYNOPSIS
  177.     BPTR fh = fdtofh(fd);
  178.     int fd;
  179.  
  180.    FUNCTION
  181.     Returns the AmigaDOS file handle associated with a file descriptor
  182.     or NULL if the file descriptor is illegal or simulated.  You may then
  183.     make AmigaDOS library calls using the file handle
  184.  
  185.    EXAMPLE
  186.  
  187.     #include <exec/types.h>
  188.  
  189.     main()
  190.     {
  191.         BPTR fh;
  192.  
  193.         write(1, "FuBar\n", 6);
  194.  
  195.         if (fh = fdtofh(1))
  196.         Write(fh, "FuBar\n", 6);
  197.  
  198.         return(0);
  199.     }
  200.  
  201.    INPUTS
  202.     int fd;     file descriptor
  203.  
  204.    RESULTS
  205.     BPTR fh;    associated file handle or NULL
  206.  
  207.    SEE ALSO
  208.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  209.     mkdir, open, read, rmdir, unlink, write
  210.  
  211.  
  212. fd/ioctl                        fd/ioctl
  213.  
  214.    NAME
  215.     ioctl - IO control on file descriptor
  216.  
  217.    SYNOPSIS
  218.     int r = ioctl(fd, req, parg1, parg2);
  219.     int fd;
  220.     int req;
  221.     int *parg1;
  222.     int *parg2;
  223.  
  224.    FUNCTION
  225.     execute an IO control on the file descriptor.  Currently no IO
  226.     controls are implemented.
  227.  
  228.    EXAMPLE
  229.  
  230.    INPUTS
  231.     int fd;     file descriptor
  232.     int req;    request from <ioctl.h>
  233.     int *parg1;    address of argument #1
  234.     int *parg2;    address of argument #2
  235.  
  236.    RESULTS
  237.     int r;        result, error if < 0.
  238.  
  239.    SEE ALSO
  240.     close, creat, fcntl, fdtofh, getfh, ioctl, isatty, lseek,
  241.     mkdir, open, read, rmdir, unlink, write
  242.  
  243.  
  244. fd/isatty                        fd/isatty
  245.  
  246.    NAME
  247.     isatty - Is a file descriptor a TTY ?
  248.  
  249.    SYNOPSIS
  250.     int r = isatty(fd);
  251.     int fd;
  252.  
  253.    FUNCTION
  254.     Returns TRUE (1) if the file descriptor is associated with a
  255.     console, FALSE (0) if not, or -1 if an error condition occurs
  256.     (such as illegal file descriptor).
  257.  
  258.    NOTE
  259.     the standard input (0), standard output (1), and standard error (2)
  260.     can all return different values for isatty() depending on how the
  261.     program is redirected.    A program whos standard in and standard out
  262.     is redirected may still have a standard error that is connected to
  263.     the console.
  264.  
  265.     refer to the file_descriptor manual page for general information
  266.  
  267.     Unlike file pointers and file handles, the file descriptor is
  268.     checked for validity and will simply return an error if illegal.
  269.  
  270.    EXAMPLE
  271.     #include <stdio.h>
  272.  
  273.     main()
  274.     {
  275.         if (isatty(1)) {
  276.         puts("input is a TTY");
  277.         } else {
  278.         puts("input is not a TTY");
  279.         }
  280.     }
  281.  
  282.     1> testprg
  283.     input is a TTY
  284.     1> echo >t:x        ; create dummy file
  285.     1> testprg <t:x
  286.     input is not a TTY
  287.     1>
  288.  
  289.    INPUTS
  290.     int fd;     file descriptor
  291.  
  292.    RESULTS
  293.     int r;        result, 1 if a tty, 0 if not, or -1 if error
  294.  
  295.    SEE ALSO
  296.     close, creat, fcntl, fdtofh, getfh, ioctl, isatty, lseek,
  297.     mkdir, open, read, rmdir, unlink, write
  298.  
  299.  
  300. fd/lseek                        fd/lseek
  301.  
  302.    NAME
  303.     lseek  - Seek within a file descriptor
  304.  
  305.    SYNOPSIS
  306.     long newpos = lseek(fd, offset, how)
  307.     int fd;
  308.     long offset;
  309.     int how;
  310.  
  311.    FUNCTION
  312.     lseek() changes where the file descriptor points to within the
  313.     open file.  You may specify an offset relative to the beginning
  314.     of the file, the current position in the file, or the end of the
  315.     file:
  316.  
  317.     how        offset
  318.     ---        ------
  319.      0        absolute offset (relative to the beginning of the file)
  320.      1        offset relative to the current position in the file
  321.      2        offset relative to the end of the file
  322.  
  323.     Negative offsets may be specified when relative modes are used.
  324.  
  325.     lseek() returns the new position in the file relative to the
  326.     beginning of the file (i.e. an absolute offset).
  327.  
  328.    NOTE
  329.     offsets are relative the how.  So, for example, if you want to seek
  330.     to the 4 character from the end of the file you would
  331.     lseek(fd, -4L, 2);
  332.  
  333.     refer to the file_descriptor manual page for general information
  334.  
  335.     Unlike file pointers and file handles, the file descriptor is
  336.     checked for validity and will simply return an error if illegal.
  337.  
  338.    EXAMPLE
  339.     #include <fcntl.h>
  340.  
  341.     main()
  342.     {
  343.         int fd;
  344.  
  345.         fd = open("t:xx", O_CREAT|O_TRUNC|O_RDWR);
  346.         if (fd >= 0) {
  347.         write(fd, "0123456789", 10);
  348.         lseek(fd, -1L, 1);
  349.         write(fd, "J", 1);  /*  overwrites the 9    */
  350.         lseek(fd, -1L, 1);
  351.         write(fd, "j", 1);  /*  overwrites the J    */
  352.         lseek(fd, -4L, 2);  /*  position over the 6 */
  353.         write(fd, "g", 1);  /*  overwrite with g, now over the 7 */
  354.         lseek(fd, 0L, 0);   /*  position over the 0 */
  355.         write(fd, "a", 1);
  356.         close(fd);
  357.         } else {
  358.         puts("Unable to create T:xx");
  359.         }
  360.     }
  361.  
  362.     1> testprg
  363.     1> type t:xx
  364.     a12345g78j
  365.     1>
  366.  
  367.    INPUTS
  368.     int fd;     file descriptor
  369.     long offset;    offset relative to how
  370.     int how;    0 = rel beginning, 1 = rel middle, 2 = rel end
  371.  
  372.    RESULTS
  373.     int newpos;    new position in file (absolute) or < 0 if error
  374.  
  375.    SEE ALSO
  376.     close, creat, fcntl, fdtofh, getfh, ioctl, isatty, lseek,
  377.     mkdir, open, read, rmdir, unlink, write
  378.  
  379.  
  380. fd/mkdir                        fd/mkdir
  381.  
  382.    NAME
  383.     mkdir  - Create a directory
  384.  
  385.    SYNOPSIS
  386.     int error = mkdir(dirname)
  387.     char *dirname;
  388.  
  389.    FUNCTION
  390.     mkdir creates a new directory.    It returns 0 if successful, -1
  391.     if not (with errno set to an error code).
  392.  
  393.    EXAMPLE
  394.     main()
  395.     {
  396.         int r;
  397.  
  398.         r = mkdir("T:tmpdir");
  399.         if (r == 0)
  400.         puts("Created T:tmpdir successfully");
  401.         else
  402.         puts("Unable to create directory T:tmpdir");
  403.     }
  404.  
  405.    INPUTS
  406.     char *dirname;    filename of directory to create
  407.  
  408.    RESULTS
  409.     int r;        0 if no error, < 0 if error
  410.  
  411.    SEE ALSO
  412.     close, creat, fcntl, fdtofh, getfh, ioctl, isatty, lseek,
  413.     mkdir, open, read, rmdir, unlink, write
  414.  
  415.  
  416. fd/open                         fd/open
  417.  
  418.    NAME
  419.     open  - open a file
  420.  
  421.    SYNOPSIS
  422.     #include <fcntl.h>
  423.  
  424.     int fd = open(name, modes);
  425.     char *name;
  426.     int modes;
  427.  
  428.    FUNCTION
  429.     Open a file of the specified name using the specified modes.  The
  430.     modes combinations yield different results as described below:
  431.  
  432.     O_RDONLY    open file for reading only
  433.     O_WRONLY    open file for writing only
  434.     O_RDWR        open file for reading and writing
  435.     O_NDELAY    open file non-blocking (not implemented)
  436.     O_APPEND    open file for writing only and force all writes to
  437.              append to the file regardless of the current seek
  438.              position.
  439.     O_CREAT     create the file if it DOES NOT exist
  440.     O_TRUNC     truncate the file if it DOES exist
  441.     O_EXCL        used only with O_CREAT, if the file already exists the
  442.             open will fail
  443.  
  444.     O_BINARY    open file for binary reading and writing, vs text.    This
  445.             flag is ignored by DICE since there is no difference on
  446.             the Amiga.    However, on IBM systems CR-LF must be
  447.             converted to an LF when reading text files.
  448.  
  449.     open returns a descriptor (>= 0) or error (< 0) on failure.
  450.  
  451.    NOTE
  452.     refer to the file_descriptor manual page for general information
  453.  
  454.     Unlike file pointers and file handles, the file descriptor is
  455.     checked for validity and will simply return an error if illegal.
  456.  
  457.    EXAMPLE
  458.     #include <fcntl.h>
  459.     #include <assert.h>
  460.  
  461.     main()
  462.     {
  463.         int fd;
  464.  
  465.         fd = open("T:xx", O_WRONLY|O_CREAT|O_TRUNC);
  466.         assert(fd >= 0);
  467.         close(fd);
  468.  
  469.         fd = open("T:xx", O_CREAT|O_EXCL|O_TRUNC|O_WRONLY);
  470.         assert(fd < 0);     /*  should fail, file already exists */
  471.         remove("T:xx");
  472.  
  473.         fd = open("T:xx", O_CREAT|O_TRUNC|O_WRONLY);
  474.         assert(fd >= 0);    /*  should work     */
  475.         write(fd, "FuBar\n", 6);
  476.         close(fd);
  477.  
  478.         fd = open("T:xx", O_APPEND|O_WRONLY);
  479.         assert(fd >= 0);
  480.         write(fd, "BxBar\n", 6);
  481.         close(fd);
  482.  
  483.         return(0);
  484.     }
  485.  
  486.     1> sampleprg
  487.     1> type t:xx
  488.     FuBar
  489.     BxBar
  490.     1>
  491.  
  492.    INPUTS
  493.     char *name;        filename to open
  494.     long modes;        modes to open the file with
  495.  
  496.    RESULTS
  497.     int fd;         A file descriptor if >= 0, an error if < 0.
  498.  
  499.    SEE ALSO
  500.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  501.     mkdir, open, read, rmdir, unlink, write
  502.  
  503.  
  504. fd/read                         fd/read
  505.  
  506.    NAME
  507.     read  - read data from a file
  508.  
  509.    SYNOPSIS
  510.     int r = read(fd, buf, bytes);
  511.     int fd;
  512.     void *buf;
  513.     int bytes;
  514.  
  515.    FUNCTION
  516.     read data from a file starting at the current seek position.  read
  517.     returns the number of bytes read or -1 if a read error occurs.
  518.  
  519.     With normal files, read will always return the number of bytes
  520.     requested until the end of file is reached, in which case read
  521.     may return fewer than the number of bytes requested.  If at the
  522.     end of a file, read will return 0.
  523.  
  524.     With devices read may or may not return the number of bytes
  525.     requested depending on the device.
  526.  
  527.    NOTE
  528.     refer to the file_descriptor manual page for general information
  529.  
  530.     Unlike file pointers and file handles, the file descriptor is
  531.     checked for validity and will simply return an error if illegal.
  532.  
  533.    EXAMPLE
  534.     #include <fcntl.h>
  535.     #include <assert.h>
  536.  
  537.     main()
  538.     {
  539.         int fd;
  540.         int r;
  541.         char buf[32];
  542.  
  543.         fd = open("T:xx", O_WRONLY|O_CREAT|O_TRUNC);
  544.         assert(fd >= 0);
  545.         write(fd, "FuBar\n", 6);
  546.         close(fd);
  547.  
  548.         fd = open("T:xx", O_RDONLY);
  549.         assert(fd >= 0);
  550.         r = read(fd, buf, sizeof(buf));     /*  sizeof(buf) == 32   */
  551.         close(fd);
  552.         assert(r == 6);
  553.  
  554.         /*
  555.          *    note that the buffer is not terminated with a nul, but since
  556.          *    we are using write() which requires a length it does not matter
  557.          */
  558.  
  559.         write(1, buf, r);
  560.     }
  561.  
  562.    INPUTS
  563.     int fd;     file descriptor to read from
  564.     void *buf;    pointer to buffer to read data into
  565.     int len;    maximum number of bytes to read
  566.  
  567.    RESULTS
  568.     int r;        number of bytes actually read (could be less than
  569.             len or 0), or < 0 if error.
  570.  
  571.    SEE ALSO
  572.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  573.     mkdir, open, read, rmdir, unlink, write
  574.  
  575.  
  576. fd/rmdir                        fd/rmdir
  577.  
  578.    NAME
  579.     rmdir - delete a directory
  580.  
  581.    SYNOPSIS
  582.     int r = rmdir(dirname);
  583.     char *dirname;
  584.  
  585.    FUNCTION
  586.     delete a directory.  The directory must be empty for the deletion to
  587.     work.
  588.  
  589.     On the Amiga this call is equivalent to remove() or unlink().
  590.  
  591.    EXAMPLE
  592.     #include <assert.h>
  593.  
  594.     main()
  595.     {
  596.         int r;
  597.  
  598.         r = mkdir("T:tmpdir");
  599.         assert(r == 0);
  600.         r = rmdir("T:tmpdir");
  601.         assert(r == 0);
  602.     }
  603.  
  604.    INPUTS
  605.     char *dirname;        name of directory to delete
  606.  
  607.    RESULTS
  608.     int r;            0 if successful, non-zero if error
  609.  
  610.    SEE ALSO
  611.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  612.     mkdir, open, read, rmdir, unlink, write
  613.  
  614.  
  615. fd/unlink                        fd/unlink
  616.  
  617.    NAME
  618.     unlink - delete a file
  619.  
  620.    SYNOPSIS
  621.     int r = unlink(filename);
  622.     char *filename;
  623.  
  624.     UNIX compatibility call, use remove() for ANSI compatibility.
  625.  
  626.    FUNCTION
  627.     delete a file, equivalent to remove(filename).  This call deletes
  628.     a file from the filesystem.
  629.  
  630.    EXAMPLE
  631.     main()
  632.     {
  633.         int r;
  634.         r = unlink("T:xx");
  635.         if (r == 0)
  636.         puts("deleted T:xx");
  637.         else
  638.         puts("unable to delete t:xx or it does not exist");
  639.     }
  640.  
  641.    INPUTS
  642.     char *filename;     name of file to delete
  643.  
  644.    RESULTS
  645.     int r;            0 if successful, non-zero if error
  646.  
  647.    SEE ALSO
  648.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  649.     mkdir, open, read, rmdir, unlink, write
  650.  
  651.  
  652. fd/write                        fd/write
  653.  
  654.    NAME
  655.     write - write data to a file
  656.  
  657.    SYNOPSIS
  658.     int r = write(fd, buf, bytes);
  659.     int fd;
  660.     void *buf;
  661.     int bytes;
  662.  
  663.    FUNCTION
  664.     writes data to a file starting at the current seek position.  This
  665.     call extends the file if necessary, else writes over existing data.
  666.  
  667.     With normal files, write will always return the number of bytes
  668.     requested and fewer only if an error occurs.
  669.  
  670.     With devices write may or may not return the number of bytes
  671.     requested depending on the device, though usually it does.
  672.  
  673.    NOTE
  674.     refer to the file_descriptor manual page for general information
  675.  
  676.     Unlike file pointers and file handles, the file descriptor is
  677.     checked for validity and will simply return an error if illegal.
  678.  
  679.    EXAMPLE
  680.     #include <fcntl.h>
  681.     #include <assert.h>
  682.  
  683.     main()
  684.     {
  685.         int fd;
  686.         int r;
  687.  
  688.         fd = open("T:xx", O_WRONLY|O_CREAT|O_TRUNC);
  689.         assert(fd >= 0);
  690.         r = write(fd, "FuBar\n", 6);
  691.         assert(r == 6);
  692.         lseek(fd, 0L, 0);       /*  seek back to beginning of file */
  693.         r = write(fd, "XX", 2);
  694.         assert(r == 2);
  695.         close(fd);
  696.     }
  697.  
  698.     1> sampleprg
  699.     1> type t:xx
  700.     XXBar
  701.     1>
  702.  
  703.    INPUTS
  704.     int fd;     file descriptor to write to
  705.     void *buf;    pointer to buffer to write data from
  706.     int len;    number of bytes to write
  707.  
  708.    RESULTS
  709.     int r;        number of bytes actually written, usually an
  710.             error if r != len.
  711.  
  712.    SEE ALSO
  713.     close, creat, fcntl, fdtofh, ioctl, isatty, lseek,
  714.     mkdir, open, read, rmdir, unlink, write
  715.  
  716.